home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Tech Arsenal 1
/
Tech Arsenal (Arsenal Computer).ISO
/
tek-03
/
datema.zip
/
DATECALC.TXT
< prev
next >
Wrap
Text File
|
1993-01-21
|
13KB
|
339 lines
DATEMATH
Working Days Calculator
(c) 1993
Table of Contents
1. Introduction (What Is DATEMATH ?)
2. A Simple Tutorial
3. The Calendar Text File
4. Compiling the Calendar File
5. DATEMATH's Library Functions
6. Oddities of Calendar Math
7. Coming Soon From Expertec
8. Registration & Legal Info
1. Introduction (What Is DATEMATH ?)
-----------------------------------------------------------------------
DATEMATH is a dynamic link library that allows developers to give their
applications the ability to real date math. While most programming
languages give you some minimal capabilities for date manipulation,
DATEMATH will allow you to add accuracy to your programs.
For instance, most language products could tell you that there is 59 days
between Jan 1, 1993 and Mar 1, 1993. But while DATEMATH can tell you that,
it can also tell you that there is 39 work days between those dates.
( If company allows more holidays, the number of work days
could be even less ).
There are three basic elements to DATEMATH. They are:
A. The DATEMATH DLL
B. The Calandar Text File
C. The Calendar Binary File
A. The DATEMATH DLL handles the three eccential date functions consisting
of DCalDIF ( a function that returns the difference in working days
between two dates), DCalADD (a function that allows you to add x number
of work days to a start date and returns the finish date), and
DCalSUB ( a function that allows you to subtract x number of work days
from a finish date and returns the start date). DATEMATH also includes
functions for loading and unloading various user calendars. Registered
users of DATEMATH will also be given access to additional functions in
DATEMATH as well as a Calendar Maintanence program.
B. The Calendar Text File is a simple ASCII file that contains a listing
of the two basic rest types, namely Rest Days and Holidays. An example
of a Rest Day is SUNDAY. Rest Days refer to Days of the Week. An example
of a Holiday is 12/25/93. Holidays refer to a specific date in time. More
on the calendar text files later.
C. The Calendar Binary File is produced when the program CalMaint.EXE
compiles the calendar text file. The DATEMATH DLL reads the calendar
binary file when the LoadCalendar Function is called. The program
CalMaint.EXE is a windows based program that is not included with
the demo version of DATEMATH. However when you register DATEMATH you
will recieve a copy of the CalMaint program at no additional cost.
More on this later.
2. A Simple Tutorial
---------------------------------------------------------------------
When you start the program the cursor will blinking in a text box labeled
start date. Type 1/1/93 and hit the {TAB} key. In the next box type
2/1/93 and hit the {TAB} key. Next Click the Difference button and
note the answer in the Results box. Next try selecting different calendars
from the Calendar Group box. As you select different calendars the results
boxes will clear. Click again on the Difference and note the new results.
Its that simple.
3. The Calendar Text File
---------------------------------------------------------------------
The Calendar Text is a simple text file that allows the developer to
define up to eight seperate work calendars. The Calendar text holds
calendar names and their respective rest and holiday information.
There is three types of data that can be in a calendar text file. They
are Rest Lines, Holiday Lines and Comment Lines.
Rest Lines and Holiday Lines are made up of two parts. The first part
is the calendar name and the second part is the day value.
Here are some examples of Rest Lines:
FiveDay Saturday
FiveDay Sunday
In the above example we have created a calendar called FiveDay and
specified Saturday and Sunday as rest days. Please note the calendar
name 'FiveDay'. One of the only rules we have when your using DATEMATH
is that calendar names cannot exceed 8 characters and the first character
must be a letter.
Here are some examples of Holiday Lines:
FiveDay 18-Jan-93
FiveDay 15-Feb-93
In this example we have specified 18-Jan-93 ( Dr. Martin Luther Kings
Birthday ) and 15-Feb-93 ( Presidents Day ) as non-work days. Each
calendar can have up to 200 holidays.
Here are some example of Comment lines
// Anything That Doesn't Look
*/ Like a Rest or Holiday
; line gets interpeted as a Comment.
Below is the Calendar Text File Used in the Sample application.
//This is the Calendar Text File (CALDATA.TXT).
// Note that the file can contain blank lines for clarity
//First I will set up a 5 day work week calendar called FiveDay.
//Calendar names can be up to 8 characters long and MUST start
//with a letter.
//Calendar FiveDay will have rest on Saturday and
//Sunday but no holidays.
//Holidays for FiveDay
//Rest for FiveDay
FiveDay sat
FiveDay sun
//Next I will set up a six day calendar that rests only on Sunday
//and has no holidays.
//Holidays for SixDay
//Rest for SixDay
SixDay sun
//Finally I will setup a calendar that rests on Saturday and Sunday
//and has standard US Holidays for 1993.
//Holidays for HolsFive
HolsFive 18-jan-93
HolsFive 25-feb-93
HolsFive 31-may-93
HolsFive 5-jul-93
HolsFive 6-sep-93
HolsFive 11-nov-93
HolsFive 25-nov-93
HolsFive 24-dec-93
HolsFive 31-dec-93
//Rest for HolsFive
HolsFive sat
HolsFive sun
4. Compiling the Calendar File
---------------------------------------------------------------------
Before DATEMATH can use the user defined calendars, the calendar text
text file must be compiled. This is done with the program CalMaint.EXE.
CalMaint first examines the calendar text file and produces a matrix
display of the users calendars. Once the you is statisfied with the
results CalMaint will compile the text file into a binary. The default
name for the Calendar Text file is Caldata.TXT. The default name for
the calendar binary file is Caldata.BIN.
The program CalMaint.EXE is not included in the demo version of
DATEMATH. However the user may test the software completely in there
own programs with the Caldata.BIN file provided. As shown in the
previous section, this calendar file has three user defined work
calendars in it.
1. FiveDay - Rest on Saturdays & Sundays, No Holidays
2. SixDay - Rest on Sundays, No Holidays
3. HolsFive- Rest on Saturdays & Sundays plus Std US Holidays for 1993
If you choose to register DATEMATH you will recieve CalMaint.exe ( so
you can compile your own calendars ) at no extra cost.
5. DATEMATH's Library Functions
---------------------------------------------------------------------
The five functions included in the DATEMATH DLL are as follows:
Function Name Ord Rcv/Snd Type Parameter Description/Sample
--------------------- --- ------- ----- --------- -------------------
LoadCalendar 1 (R) LPINT nMemRef memory tag
(S) LPSTR szCalFile 'c:\caldata.bin'
DCalDIF 2 (S) LPINT nMemRef memory tag
(S) LPSTR szCalendar 'ADMIN'
(S) LPSTR szStartDate '1993-01-01'
(S) LPSTR szFinDate '1993-01-31'
(R) LPINT nDaysDif result difference in days
DCalADD 3 (S) LPINT nMemRef memory tag
(S) LPSTR szCalendar 'ADMIN'
(S) LPSTR szDateIn '1993-01-01'
(R) LPSTR szDateOut date result
(S) LPINT nDaysAmt days to add
DCalSUB 4 (S) LPINT nMemRef memory tag
(S) LPSTR szCalendar 'ADMIN'
(S) LPSTR szDateIn '1993-01-01'
(R) LPSTR szDateOut date result
(S) LPINT nDaysAmt days to substract
DestroyCalendar 5 (R) LPINT nMemRef releases calendar memory
They are defined in Visual Basic AS:
Declare Function LoadCalendar Lib "DateMath.DLL" (nMemRef%, ByVal szCalFile$) As Integer
Declare Function DCalDIF Lib "DateMath.DLL" (nMemRef%, ByVal szCalendar$, ByVal szStart$, ByVal szFinish$, nDaysDif%) As Integer
Declare Function DCalADD Lib "DateMath.DLL" (nMemRef%, ByVal szCalendar$, ByVal szStart$, ByVal szFinish$, nDaysDif%) As Integer
Declare Function DCalSUB Lib "DateMath.DLL" (nMemRef%, ByVal szCalendar$, ByVal szStart$, ByVal szFinish$, nDaysDif%) As Integer
Declare Function DestroyCalendar Lib "DateMath.DLL" (nMemRef%) As Integer
6. Oddities of Calendar Math
---------------------------------------------------------------------
If you're new to doing 'Work Day' calendar math you may occasionally
come across results you don't expect. The best way to illustrate
this is with an example.
First lets consider the months of January 1993 & February 1993.
January 1993 February 1993
Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa
1 2 1 2 3 4 5 6
3 4 5 6 7 8 9 7 8 9 10 11 12 13
10 11 12 13 14 15 16 14 15 16 17 18 19 20
17 18 19 20 21 22 23 21 22 23 24 25 26 27
24 25 26 27 28 29 30 28
31
Assuming that all Saturdays and Sundays are rest days, consider the
following two statements:
The difference between 1-Jan-93 and 31-Jan-93 is 21 work days.
The difference between 1-Jan-93 and 1-Feb-93 is 21 work days.
Both these statemnts are true. ( Since 31-Jan-93 is a rest day)
Continuing along line, consider these statements:
1-Jan-93 plus 21 work days equals 1-Feb-93.
31-Jan-93 minus 21 work days equals 1-Jan-93.
When adding or subtracting work days from a date the result is
always a work day.
Hopefully this breif explantion will help you if you find yourself
confused about the results DATEMATH produces.
7. Coming Soon From Expertec
---------------------------------------------------------------------
Expertec Incorporated has been in the business of writing custom
software for Fortune 500 companies since 1989. At Expertec we
specialize in the development of Project Management and Expert
Systems. The majority of our work is in the client-server arena
primarily on Windows,Windows NT, and Unix platforms.
DATEMATH comes from the Project Management side of the house and
is primarily the of work Paul Onstad. Another of Mr. Onstads programs
that may be of interest is the Expertec CPM Engine. The CPM Engine
is a set of DLL's that allow the developer to perform Critical
Path Analysis routines on there databases. The product generates
all standard CPM dates including Early Start, Early Finish,
Late Start, Late Finish as well as Total and Free floats. The CPM
engine also allows six different Target Date types and uses the same
calendar files as DATEMATH. The product is currently available
for developers using Gupta Technologies SQLWindows language and will
be available for Microsoft Access developers in the 2nd Qtr. 1993.
Suggested Retail Price for the CPM engine is $99.95
8. Registration & Legal Info
---------------------------------------------------------------------
Money Stuff:
DATEMATH is not free. It is a commercial Shareware product. You
are permited to evaluate this product for 15 days. After that time
you must register or discontinue using the program.
The use of unregistered copies of DATEMATH, beyond the evaluation
period, by any person, business, corporation, government agency or
any other entity is strictly prohibited. The basic registration fee
for DATEMATH is $24.95($15.00 before 31-Mar-93). For instructions
on how to register, see the file REGISTER.TXT.
Whether or not you choose to register, I'd enjoy hearing your comments
on the program. Please send all suggestions, gripes, bug reports and
anything else to any of these addresses:
Expertec, Inc.
Attn: Chet Kloss
340 North Main Street - Suite 304
Plymouth, MI 48170
CIS: 72311,743
The latest version of DATEMATH can be found on the MSBASIC forum of CIS.
Legal Stuff:
No guarantee is made, expressed or implied, pertaining to the use,
misuse,or any problems caused by this program. Should the program
prove defective, the purchaser or evaluator assumes the risk of paying
the entire cost of all necessary servicing, repair, or correction, and
any incidental or consequential damages. In no event will the author
be liable for any damages whatsoever arising out of the use or the
inability to use this product.
A limited license is granted to copy and distribute DATEMATH for
the evaluation use of others, as long as it is distributed without
modification, complete with all files. No fee, charge or other
compensation may be requested with these exceptions:
Operators of electronic bulletin board systems may make DATEMATH
available for downloading, so long as there is no specific charge
for the download of DATEMATH. Vendors of user-supported or shareware
software may distribute DATEMATH, so long as any duplication and
handling fees do not exceed five dollars, and notice is clearly given
that such fees do not grant the evaluator a license to use DATEMATH
beyond the evaluation period.